Description

This PR proposes adding lockForUpdate() to the Query Builder for pessimistic write locking on supported database drivers.

The goal is to provide a small framework-native API for code that needs to read rows and then safely update them inside the same transaction.

Example:

$db->transaction(static function ($db) use ($accountId): void {
    $account = $db->table('accounts')
        ->where('id', $accountId)
        ->lockForUpdate()
        ->get()
        ->getRow();

    // Use $account to update the locked row safely...
});

Why

Some application workflows need to prevent concurrent writes around the same row while a transaction is deciding what to do next.

Common examples include:

• checking and updating account balances
• assigning the next pending job or record
• preventing two workers from processing the same row
• updating counters or limited-capacity resources
• safely reading a row before applying a state transition

Without a Query Builder method, users either need raw SQL per database driver or custom helper code around otherwise builder-based queries.

Behavior

For drivers that support a trailing FOR UPDATE clause, lockForUpdate() appends it to the compiled SELECT.

SQLSRV is handled separately because SQL Server does not use trailing FOR UPDATE. Instead, it applies WITH (UPDLOCK, ROWLOCK) table hints to table references in the FROM clause.

Supported drivers in this PR:

• MySQLi
• Postgre
• OCI8
• SQLSRV

Unsupported or constrained behavior:

• SQLite3 throws DatabaseException because SQLite does not support row-level SELECT ... FOR UPDATE.
• OCI8 throws DatabaseException when lockForUpdate() is combined with limit() or offset(), because Oracle does not allow FOR UPDATE with row limiting.
• SQLSRV throws DatabaseException when used without a FROM table or on subqueries.
• SQLSRV does not hint joined tables in this implementation because joins are already stored as compiled SQL strings.

Notes

This PR intentionally keeps the first implementation narrow. It does not add sharedLock(), skipLocked(), nowait() or SQLSRV joined-table hinting.

Those could be considered later, but this PR focuses only on the most common pessimistic write-lock use case.

Testing

Added Query Builder coverage for:

• generic FOR UPDATE compilation
• reset and $reset = false behavior
• countAllResults() suppressing lock clauses
• OCI8 support and limit/offset restriction
• SQLite3 unsupported-driver behavior
• SQLSRV table hints
• SQLSRV aliases, limits, joins, subqueries, and no-FROM queries

Checklist

• Securely signed commits
• Component(s) with PHPDoc blocks, only if necessary or adds value (without duplication)
• Unit testing, with >80% coverage
• User guide updated
• Conforms to style guide